Skip to content

Highlight CQL and other new languages, and refresh the highlighting theme - #213

Merged
eric-schneider merged 10 commits into
mainfrom
syntax-highlight-fixes
Sep 30, 2026
Merged

eric-schneider merged 10 commits into
mainfrom
syntax-highlight-fixes

Conversation

@eric-schneider

@eric-schneider eric-schneider commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Jira: DOC-3966

Summary

  • CQL code blocks get real CQL highlighting. Until now, cql was an alias for the SQL grammar. It is now highlightjs-cql, a grammar built for CQL. It covers Apache Cassandra, DataStax Enterprise, HCD, and Astra DB, and it was tested against Cassandra's own parser.
  • GraphQL code blocks are highlighted. highlight.js 9 has no GraphQL grammar, so these blocks were plain text. The grammar is ported from highlight.js 11.
  • A refreshed syntax theme for every language.
    • Each kind of token has its own color from our existing palette.
    • Every color meets WCAG AA contrast (4.5:1) in both light and dark mode. Before, strings, numbers, types, and function names failed it in light mode, as low as 3.41:1.
    • The error red is no longer used for ordinary code.
  • The vendor scripts are minified, as the build intended. A misplaced parenthesis in gulp.d/tasks/build.js had skipped all of them. A first visit now downloads 88 KB of these scripts compressed instead of 113 KB, and the highlighting bundle drops from 56 KB to 35 KB. License notices are kept through minification, and the zooming and Floating UI bundles get the MIT notices they lacked.
  • Protobuf and PowerShell code blocks are highlighted. The redundant toml registration is dropped, since the ini grammar already answers to toml.
  • The UI preview gets syntax highlighting samples on its Code page.

New theme (light and dark modes)

theme-final-sky

How to review

UI preview. Open the Code page, then its "Syntax highlighting samples" section. Check it in both light and dark mode. Link: https://d5rxiv0do0q3v.cloudfront.net/docs-ui-drafts/syntax-highlight-fixes/asciidoc/code.html#syntax-highlighting-samples

Draft docs site. After this PR is merged, when we open the PR to update the UI bundle in the datastax-docs-site repo, open the full site draft build and compare these pages with production, in both light and dark mode:

Page What to look for
Vector search quickstart (CQL docs) Functions like now() and types like VECTOR<FLOAT, 5> get their own colors. Column names such as id and comment are no longer colored as keywords.
UPDATE (CQL command reference) Placeholders like <list_name> in the syntax summaries are italic.
Multi-faceted search using healthcare data (CQL docs, DSE versions) DSE Search syntax, plus XML that was almost entirely red before.
Migrate to the Data API from the Stargate APIs (Astra DB Serverless) 19 GraphQL blocks that were plain text before.
About Change Data Capture (CDC) workflows with Apache Cassandra and Apache Pulsar The new theme across nine languages on one page.
Back up data (Mission Control) YAML keys are colored (they were uncolored before) and values are readable.

Minified scripts. In the UI preview, open the highlighting script in the browser's developer tools. It's minified, and it starts with the license notices.

Accessibility. In a sample of 246 colored tokens across the 14 most common languages in the docs, 101 failed WCAG AA contrast in light mode before this change, and 10 in dark mode. None do now.

Notes for reviewers

  • Vendored grammars. src/js/vendor/languages/ holds grammars that are maintained elsewhere. Its README says where each comes from and how to update it. Lint and format skip this folder, because the files keep their upstream formatting.

  • License notice. A comment at the top of highlight.bundle.js lists the bundled highlighting code and its licenses:

    • highlight.js (BSD-3-Clause)
    • the GraphQL port (BSD-3-Clause)
    • highlightjs-curl (Apache-2.0)
    • highlightjs-cql (Apache-2.0)

    The comment is carried into the published bundle. The build now puts back any license notice that minification drops.

  • Colors. Syntax colors are new --ds-code-* variables in src/css/vars/light.css and src/css/vars/dark.css. They use shade 700 of each palette color in the light theme and shade 400 in the dark theme.

  • Prompts. cqlsh prompts (cqlsh>) can't be selected, the same as console prompts.

  • Not addressed here (pre-existing): the toolchain pins Node 16, and npm install reports dependency vulnerabilities.

- Register highlightjs-cql 1.0.0 for cql and cqlsh blocks, replacing the SQL
  stand-in. It colors CQL by role (types, names, setting names, functions,
  bind markers, cqlsh prompts and commands) for Apache Cassandra, DSE, HCD,
  and Astra DB.
- Register GraphQL (graphql, gql), ported from highlight.js 11.12.0, which
  highlight.js 9 lacks. Output matches highlight.js 11 on all 19 GraphQL
  blocks in the docs.
- Add a license notice for the bundled highlighting code to the top of
  highlight.bundle.js.
- Style placeholders (<keyspace_name>) in italics instead of the error color.
- Keep lint and format off src/js/vendor/languages, which holds grammars
  maintained elsewhere.
- Give each kind of token its own color: keywords purple, types cyan,
  functions and headings pink, keys and setting names indigo, strings green,
  numbers and literals orange, variables and placeholders amber, prompts and
  comments gray, deleted lines red.
- Meet WCAG AA contrast (4.5:1) in both themes. The colors come from new
  --ds-code-* variables: shade 700 of each palette family in the light theme
  and shade 400 in the dark theme. Before, strings, numbers, types, literals,
  and function names were below 4.5:1 in the light theme (as low as 3.41:1),
  and variables and XML names were below it in the dark theme (3.96:1).
- Stop using the error color for variables and markup, and stop coloring
  whole parameter lists.
- Italicize comments. Placeholders stay italic.
- Make cqlsh prompts unselectable, like console prompts.
Setting names (such as REPLICATION in WITH REPLICATION = ...) were indigo,
next to purple keywords: a color difference (CIEDE2000) of only 8.9 in the
light theme, and harder still to tell apart in capital letters. They are
now cyan, a difference of 28.9. Types and built-ins move from cyan to lime,
which also keeps them far from the keywords they sit beside (TEXT PRIMARY
KEY). Both colors still meet WCAG AA contrast in both themes.
The preview's code page had one CQL block and no GraphQL, YAML, or XML,
so a reviewer of the UI preview couldn't see most of what this branch
changes. Add a "Syntax highlighting samples" section with CQL statements,
a CQL syntax summary with placeholders, a cqlsh session, GraphQL, YAML,
and XML. Preview pages aren't part of the UI bundle.
IBM Docs, where these docs are moving, reads the language name exactly
as written, so a block labeled [source,language-cql] isn't highlighted
there. Normalizing the label here would hide that problem from writers.
Without the normalization, such blocks are plain on this site too, which
shows that the label needs fixing.

Protobuf highlighting, added in the same earlier commit, stays.
The vendor scripts were meant to be minified, all except floatingui.js,
but a misplaced parenthesis made the build skip all of them. Minify them
as intended, with a per-file condition.

- Minifying drops the license notices from the highlight.js bundle, which
  its BSD license requires us to keep. Record each bundle's /*! ... */
  notices before minifying and put back any that are lost.
- The zooming and Floating UI bundles carried no license notice at all,
  though their MIT licenses ask for one. Add one to each.
- A first visit now downloads 88 KB of these scripts compressed, instead
  of 113 KB. The highlight.js bundle drops from 56 KB to 35 KB.
This brings in the change from the powershell-highlighting branch.

- Register highlight.js's PowerShell grammar, which also answers to ps
  and ps1. The Astra CLI's Windows instructions and the C# driver's
  NuGet commands are PowerShell, now labeled shell and cs; relabeled,
  they'll be highlighted here and on IBM Docs.
- Stop registering the INI grammar a second time as toml. The INI
  grammar already answers to toml.
- Add a PowerShell sample to the UI preview, since no page labels
  a block powershell yet.
Match highlightjs-cql's dist/cql.cjs, which rewords one comment about
DataStax Enterprise's PENDING keyword. Highlighting is unchanged.
Setting names share their color with JSON and YAML keys, XML attribute
names, and GraphQL argument names. The cyan in use now is only 25 apart
from string values (CIEDE2000), and the indigo before it only 8.9 from
keywords in light mode. Sky is at least 28.8 from keywords and 33.3 from
strings, in both themes.

- Contrast on the code background is 5.68:1 in light mode (sky 700)
  and 6.95:1 in dark mode (sky 400). Every highlighted token in the UI
  preview still passes WCAG AA in both themes.
@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

UI bundle preview build successful! ✅
Deploying bundle preview.
Deploy successful! View preview

@plpesvc-ds

plpesvc-ds commented Sep 25, 2026 •

Copy link
Copy Markdown

Build successful! ✅
Deploying draft.
Deploy successful! View draft

@eric-schneider eric-schneider linked an issue Sep 25, 2026 that may be closed by this pull request
@eric-schneider eric-schneider changed the title Highlight CQL and GraphQL, and refresh the syntax highlighting theme Highlight CQL and other languages, and refresh the syntax highlighting theme Sep 30, 2026
@eric-schneider eric-schneider changed the title Highlight CQL and other languages, and refresh the syntax highlighting theme Highlight CQL and other new languages, and refresh the highlighting theme Sep 30, 2026
@eric-schneider
eric-schneider merged commit d233a5a into main Sep 30, 2026
2 checks passed
@eric-schneider
eric-schneider deleted the syntax-highlight-fixes branch September 30, 2026 06:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

CQL highlighting

2 participants